/*
 * Copyright 2002-2007 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanFactory;

/**
 * #Comment#:定义了将容器中的Bean按照某种规则（按名称匹配、类型匹配等）进行自动装配的方法。<br/>
 * Extension of the {@link org.springframework.beans.factory.BeanFactory}
 * interface to be implemented by bean factories that are capable of autowiring,
 * provided that they want to expose this functionality for existing bean
 * instances.
 * 
 * <p>
 * This subinterface of BeanFactory is not meant to be used in normal
 * application code: stick to
 * {@link org.springframework.beans.factory.BeanFactory} or
 * {@link org.springframework.beans.factory.ListableBeanFactory} for typical use
 * cases.
 * 
 * <p>
 * Integration code for other frameworks can leverage this interface to wire and
 * populate existing bean instances that Spring does not control the lifecycle
 * of. This is particularly useful for WebWork Actions and Tapestry Page
 * objects, for example.
 * 
 * <p>
 * Note that this interface is not implemented by
 * {@link org.springframework.context.ApplicationContext} facades, as it is
 * hardly ever used by application code. That said, it is available from an
 * application context too, accessible through ApplicationContext's
 * {@link org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()}
 * method.
 * 
 * <p>
 * You may also implement the
 * {@link org.springframework.beans.factory.BeanFactoryAware} interface, which
 * exposes the internal BeanFactory even when running in an ApplicationContext,
 * to get access to an AutowireCapableBeanFactory: simply cast the passed-in
 * BeanFactory to AutowireCapableBeanFactory.
 * 
 * @author Juergen Hoeller
 * @since 04.12.2003
 * @see org.springframework.beans.factory.BeanFactoryAware
 * @see org.springframework.beans.factory.config.ConfigurableListableBeanFactory
 * @see org.springframework.context.ApplicationContext#getAutowireCapableBeanFactory()
 */
public interface AutowireCapableBeanFactory extends BeanFactory {

	/**
	 * Constant that indicates no autowiring at all (other than callbacks such
	 * as BeanFactoryAware).
	 * 
	 * @see #createBean
	 * @see #autowire
	 * @see #autowireBeanProperties
	 */
	int AUTOWIRE_NO = 0;

	/**
	 * Constant that indicates autowiring bean properties by name.
	 * 
	 * @see #createBean
	 * @see #autowire
	 * @see #autowireBeanProperties
	 */
	int AUTOWIRE_BY_NAME = 1;

	/**
	 * Constant that indicates autowiring bean properties by type.
	 * 
	 * @see #createBean
	 * @see #autowire
	 * @see #autowireBeanProperties
	 */
	int AUTOWIRE_BY_TYPE = 2;

	/**
	 * Constant that indicates autowiring a constructor.
	 * 
	 * @see #createBean
	 * @see #autowire
	 */
	int AUTOWIRE_CONSTRUCTOR = 3;

	/**
	 * Constant that indicates determining an appropriate autowire strategy
	 * through introspection of the bean class.
	 * 
	 * @see #createBean
	 * @see #autowire
	 */
	int AUTOWIRE_AUTODETECT = 4;

	/**
	 * Fully create a new bean instance of the given class with the specified
	 * autowire strategy. All constants defined in this interface are supported
	 * here.
	 * <p>
	 * Performs full initialization of the bean, including all applicable
	 * {@link BeanPostProcessor BeanPostProcessors}.
	 * 
	 * @param beanClass
	 *            the class of the bean to create
	 * @param autowireMode
	 *            by name or type, using the constants in this interface
	 * @param dependencyCheck
	 *            whether to perform a dependency check for objects (not
	 *            applicable to autowiring a constructor, thus ignored there)
	 * @return the new bean instance
	 * @throws BeansException
	 *             if instantiation or wiring failed
	 * @see #AUTOWIRE_NO
	 * @see #AUTOWIRE_BY_NAME
	 * @see #AUTOWIRE_BY_TYPE
	 * @see #AUTOWIRE_CONSTRUCTOR
	 * @see #AUTOWIRE_AUTODETECT
	 */
	Object createBean(Class beanClass, int autowireMode, boolean dependencyCheck)
			throws BeansException;

	/**
	 * Instantiate a new bean instance of the given class with the specified
	 * autowire strategy. All constants defined in this interface are supported
	 * here.
	 * <p>
	 * Does <i>not</i> apply any {@link BeanPostProcessor BeanPostProcessors} or
	 * perform any further initialization of the bean. This interface offers
	 * distinct, fine-grained operations for those purposes, for example
	 * {@link #initializeBean}.
	 * 
	 * @param beanClass
	 *            the class of the bean to instantiate
	 * @param autowireMode
	 *            by name or type, using the constants in this interface
	 * @param dependencyCheck
	 *            whether to perform a dependency check for object references in
	 *            the bean instance (not applicable to autowiring a constructor,
	 *            thus ignored there)
	 * @return the new bean instance
	 * @throws BeansException
	 *             if instantiation or wiring failed
	 * @see #AUTOWIRE_NO
	 * @see #AUTOWIRE_BY_NAME
	 * @see #AUTOWIRE_BY_TYPE
	 * @see #AUTOWIRE_CONSTRUCTOR
	 * @see #AUTOWIRE_AUTODETECT
	 * @see #initializeBean
	 * @see #applyBeanPostProcessorsBeforeInitialization
	 * @see #applyBeanPostProcessorsAfterInitialization
	 */
	Object autowire(Class beanClass, int autowireMode, boolean dependencyCheck)
			throws BeansException;

	/**
	 * Autowire the bean properties of the given bean instance by name or type.
	 * 
	 * @param existingBean
	 *            the existing bean instance
	 * @param autowireMode
	 *            by name or type, using the constants in this interface
	 * @param dependencyCheck
	 *            whether to perform a dependency check for object references in
	 *            the bean instance
	 * @throws BeansException
	 *             if wiring failed
	 * @see #AUTOWIRE_BY_NAME
	 * @see #AUTOWIRE_BY_TYPE
	 */
	void autowireBeanProperties(Object existingBean, int autowireMode,
			boolean dependencyCheck) throws BeansException;

	/**
	 * Apply the property values of the bean definition with the given name to
	 * the given bean instance. The bean definition can either define a fully
	 * self-contained bean, reusing its property values, or just property values
	 * meant to be used for existing bean instances.
	 * <p>
	 * Note: This method does <i>not</i> autowire bean properties; it just
	 * applies explicitly defined property values. Use the
	 * {@link #autowireBeanProperties} method to autowire an existing bean
	 * instance.
	 * 
	 * @param existingBean
	 *            the existing bean instance
	 * @param beanName
	 *            the name of the bean definition in the bean factory (a bean
	 *            definition of that name has to be available)
	 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
	 *             if there is no bean with the given name
	 * @throws BeansException
	 *             if applying the property values failed
	 * @see #autowireBeanProperties
	 */
	void applyBeanPropertyValues(Object existingBean, String beanName)
			throws BeansException;

	/**
	 * Configure the given bean instance: autowiring bean properties, applying
	 * bean property values, applying factory callbacks such as
	 * <code>setBeanName</code> and <code>setBeanFactory</code>, and also
	 * applying all bean post processors.
	 * <p>
	 * This is effectively a superset of what <code>initializeBean</code>
	 * provides, fully applying the configuration specified by the corresponding
	 * bean definition.
	 * 
	 * @param existingBean
	 *            the existing bean instance
	 * @param beanName
	 *            the name of the bean, to be passed to it if necessary (a bean
	 *            definition of that name has to be available)
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws org.springframework.beans.factory.NoSuchBeanDefinitionException
	 *             if there is no bean with the given name
	 * @throws BeansException
	 *             if the initialization failed
	 * @see #initializeBean
	 */
	Object configureBean(Object existingBean, String beanName)
			throws BeansException;

	/**
	 * Initialize the given bean instance, applying factory callbacks such as
	 * <code>setBeanName</code> and <code>setBeanFactory</code>, also applying
	 * all bean post processors.
	 * <p>
	 * Note that no bean definition of the given name has to exist in the bean
	 * factory. The passed-in bean name will simply be used for callbacks but
	 * not checked against the registered bean definitions.
	 * 
	 * @param existingBean
	 *            the existing bean instance
	 * @param beanName
	 *            the name of the bean, to be passed to it if necessary (only
	 *            passed to {@link BeanPostProcessor BeanPostProcessors})
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws BeansException
	 *             if the initialization failed
	 */
	Object initializeBean(Object existingBean, String beanName)
			throws BeansException;

	/**
	 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing
	 * bean instance, invoking their
	 * <code>postProcessBeforeInitialization</code> methods. The returned bean
	 * instance may be a wrapper around the original.
	 * 
	 * @param existingBean
	 *            the new bean instance
	 * @param beanName
	 *            the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws BeansException
	 *             if any post-processing failed
	 * @see BeanPostProcessor#postProcessBeforeInitialization
	 */
	Object applyBeanPostProcessorsBeforeInitialization(Object existingBean,
			String beanName) throws BeansException;

	/**
	 * Apply {@link BeanPostProcessor BeanPostProcessors} to the given existing
	 * bean instance, invoking their <code>postProcessAfterInitialization</code>
	 * methods. The returned bean instance may be a wrapper around the original.
	 * 
	 * @param existingBean
	 *            the new bean instance
	 * @param beanName
	 *            the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one
	 * @throws BeansException
	 *             if any post-processing failed
	 * @see BeanPostProcessor#postProcessAfterInitialization
	 */
	Object applyBeanPostProcessorsAfterInitialization(Object existingBean,
			String beanName) throws BeansException;

}
